Tasking Design Descriptions 



A guiding rule of software development is that no one likes to 
document their code. Here's how to make the paperwork less painful. 



Mention documenta- 
tion to engineers, 
and their eyes 
become glassy, their 
pupils dilate, and 
their palms sweat. Documentation is 
the ultimate bugaboo for all of us. But, 
as the mildly scatological cartoon in 
many offices reminds us, "The job's 
not done until the paperwork is done." 
Writing is easy, if you know where to 
start and what you want to say. This 
article will offer some guidelines to 
make writing tasking design docu- 
ments easier and much less painful. 

Several years ago, we encountered 
an unusual problem. One of our cus- 
tomers insisted that we change from 
one real-time executive to another. Our 
system had been in use for some time 
and worked well. To make the change, 
we had to map one set of tasking 
abstractions to another. No problem, 
we thought, we have good documenta- 
tion. Our documentation, however, had 
almost nothing to say about the tasks, 



interrupt-service routines (ISRs), and 
their interactions. The only place we 
could find this information was in the 
source listings. Needless to say, the 
process was slow and labor intensive. 
The service calls were easy to find; 
finding the single bit embedded in a 
table took a lot longer. 

Shortly after the conversion job, the 
boss asked me to look at a large design 
document (about five inches thick) that 
supposedly described a system of some 
120 tasks and several dozen ISRs. It 
contained very little useful informa- 
tion. Based on our conversion experi- 
ence, we reduced that monster design 
document to a fraction of its original 
size, with considerably more useful 
information. Since then, we've used 
this method to describe a number of 
tasking designs, some as small as five 
tasks, but most somewhat larger. 
Hardware system engineers, cus- 
tomers, performance analysts, testers, 
and maintenance engineers have all 
commented favorably on this method. 



MOVING AND SHAKING 

We begin by drawing a graph- 
ical description of the task- 
ing design using the sym- 
bols in Figure 1. Boxes or squares rep- 
resent physical devices. Interrupts to 
ISRs are shown by broken lines, and 
ISRs shown as circles. Also, we'll use 
circles for tasks, processes, and other 
asynchronously executed software. 
Queues of commands or buffers will 
be shown with a fat letter I and sema- 
phores with a skinny letter I. Optional 
time-outs will be represented with a 
small triangle, and data stores or tables 
will be shown by a 'container' silhou- 
ette. A shared resource, which needs 
concurrent access protection, is shown 
by a rectangle. 

There is nothing sacrosanct about 
these symbols. You may. use whatever 
is appropriate on whatever CASE tool 
you choose. You can add symbols, if 
you like, to represent event flags, 
pipes, mailboxes, and so on. 

Each entity should be labeled or 
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named. I suggest using long and short 
form names as used in the program 
source code for each entity. Data-flow 
lines should be drawn to or from 
devices and buffers, and from tasks to 
buffers, or tasks to tasks as appropri- 
ate. Interrupts are drawn from devices 
to their associated ISRs. Signals from 
one task to another can be shown as 
interrupts, since that is what the signal 
looks like. Each line should be labeled 
or named. 

Explicit controls should also be 
drawn. For example, task A activates 
task B and later suspends and resumes 
it. A labeled dotted or dashed line from 
task A to task B is adequate, even 
though these controls are really service 
calls to the executive. Hidden tasks, 
some times called demons, should be 
shown. Several well-known real-time 



executives use their own tasking ser- 
vices to implement other tasking fea- 
tures. For example, one executive for 
the 68HC1 1 uses an executive task to 
field timer interrupts that in turn acti- 
vates application-level periodic tasks. 
These hidden tasks consume overhead 
and can cause interrupt latency prob- 
lems. By explicitly documenting these 
tasks, maintenance engineers and users 
are warned about nonapplication tasks 
that could cause problems. 

DOCUMENTING THE PROCESS 

Once the diagram is complete, 
or nearly so, we can begin to 
document what's going on. 
For every line, entity, or element on the 
diagram, you should have one or two 
sentences describing that element. 
More may be written as you see fit. In 



FIGURE 1 

Example symbols. 




concurrent 
task or process 



physical 
device 



queue 



semaphore 
or event flag 



semaphore 
or event flag 
with timer 



data store 



shared 
resource 



interrupt 
or signal 
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Some ISRs may be 
invoked by tasks, 
and some devices 
may generate 
more than one 
interrupt for each 
I/O request. 

addition, three of the element types, 
tasks, ISRs, and shared resources, have 
key features you'll want to document. 
Let's start with tasks. For each task (or 
task type if a family of tasks is used), 
describe the following: 

• Name — give both the long English 
name and source code name. 

• Purpose — state what this task does. 
Leave the details to the detail design 
description or source code. 

• Frequency — state the frequency or 
period of execution. For periodic tasks, 
hard-deadline tasks, or asynchronous 
tasks with response time requirements, 
the period needs to be identified. 
Minimum interarrival time of aperiod- 
ic tasks should be stated. Operational 
profiles may be useful here. 



• Execution time — depending on your 
needs, give some estimate of or limita- 
tion on CPU use or time. 

• Sequencing or control — state all con- 
ditions under which this task starts, 
stops, or blocks. Identify the agents 
responsible. If the task never termi- 
nates, say so. Identify all blocking 
points in the task. These will give 
insight into rescheduling points. 

• Priority — state the priority of the 
task. If the priority is variable, state the 
values or ranges and give the mecha- 
nism and reason. 

• Input and output — identify top-level 
data flowing in and out of the task. 

• Blocking time — if the task uses a 
shared resource, give the amount of 
time the resource is locked by the task. 

• Other executive services — executive 
or kernel services not otherwise given 
in the previous items should be called 
out. 

ISRs receive the same treatment as 
tasks: 

• Name — do the same as for tasks. 

• Purpose — state what this ISR does. 
Identify the interrupts serviced by this 
ISR. 

• Frequency — remember that some 
ISRs may be invoked by tasks, and 
some devices may generate more than 
one interrupt for each I/O request. 

• Execution time — give execution times 
for each kind of device and interrupt. 

• Sequencing or control — state all con- 



ditions, including hardware and soft- 
ware interrupts, that start this ISR. 
State the exit destination of this ISR. If 
this ISR changes the interrupt lock-out, 
enables, or priorities, include that 
description. Describe the execution 
environment and any restrictions on 
reentrancy. 

• Priority — state the assigned priority 
level if supported by the hardware. 

• Input and output — identify the inputs 
and outputs; usually these are com- 
mands and status data and not applica- 
tion data. 

• Executive services — be sure to 
describe specific kernel services used 
by the ISR since they may not be 
explicitly shown on the diagram. 

The last elements . needing special 
attention are shared resources: 

• Name — give the name of the 
resource. 

• Purpose — state the purpose of the 
resource. 

• Synchronization mechanism — identi- 
fy the method used to serialize access 
to this resource; for example, sema- 
phore, critical section, and so on. 
Identify time-out intervals if used. 

Let's illustrate this method by 
describing part of a simple system as 
shown in Figure 2. This sub-system 
consists of an I/O device server task 
and its associated device interrupt-ser- 
vice routine. 
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• Name — device. task (devtsk). 

• Purpose — the device.task manages 
I/O requests from application tasks by 
PENDing on the request.queue. When the 
device.task receives a request, it WAITs 
on the request.sema semaphore until the 
i/o.req register is free. When the 
i/o_req register is free, the task writes 
the request data in the i/o_req register 
and SIGNALS the device.isr. The task 
does a timed WAIT on the i/o_complete 
semaphore. When the device.isr 
SIGNALS the i/o_complete semaphore or 
the time-out occurs, the kernel restarts 
the device.task. The device.task reads 
the status_ind register and restarts the 
associated application task. The 
device.task PENDs on the request.queue 
for the next I/O operation. 

• Frequency — aperiodic. Device.task is 
driven at the frequency of the request- 
ing tasks. 

FIGURE 2 

' detailed example. 



• Execution time — the average execu- 
tion time of this task is 830 microsec- 
onds including kernel service times. 

• Sequencing — this task is started by 
the initialization task, and it never ter- 
minates. This task may be blocked on 
the request.queue and the request.sema, 
and it will block on the i/o_complete 
semaphore. The signal operation on the 
device.isr will cause the device.task to 
be interrupted, and it may be delayed 
in its execution by the kernel dispatch- 
ing another task. Restarting the 
requesting task may block the 
device.task. 

• Priority — this task operates at priori- 
ty level 3. A higher priority may result 
in excessive I/O operations and delays 
to application tasks, while a lower pri- 
ority level may result in excessive 
queuing delays. 

• Input and output — this task receives 



The ISR manages 
the device I/O by 
setting up 




registers and 
interpreting device 
status. 



I/O requests from the request queue 
and status data from the device_isr and 
sends I/O commands to the device.isr. 

• Blocking time — N/A. 

• Other executive services — N/A. 

• Name — device_isr. 

• Purpose — this ISR manages the 
device I/O by setting up command reg- 
isters and interpreting device status. 

• Frequency — this ISR is driven by the 
frequency of requests from the associ- 
ated device task. 

• Execution time — this ISR takes a 
total of 67 microseconds to service one 
request and its interrupt. 

• Sequencing and control — this ISR is 
started by a signal interrupt from the 
device.task and an interrupt from the 
device. It exits to the kernel interrupt 
return entry point. It SIGNALS the 
request.sema after reading the i/o_req 
register and SIGNALS the i/o_complete 
semaphore when the I/O operation is 
complete. 

• Priority — device.isr operates at inter- 
rupt priority level 2, channel priority 
level 5. 

• Input and output — device.isr receives 
I/O request data from the device.task 
and status data from the device. It 
sends commands to the device and sta- 
tus indications to the device.task. 

• Executive services — N/A. 

To reduce the clutter in Figure 2, we 
have not shown labels on the lines, 
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but you should label all the lines on 
your drawings. 

These guidelines are powerful and 
useful. You write only what you need 
to write, no more and no less. 
Engineers often don't know what to 
write and once started don't know 
when to quit. As a result, real informa- 
tion content is low, and the resulting 
document becomes bulky, unreadable, 



and unread. 

When engineers first attempt to use 
this method of tasking design descrip- 
tion, their diagrams tend to be too sim- 
ple. That is, they don't have enough 
elements (graphics) to capture the 
essence of the design. The details on 
physical interfaces are usually ignored 
or forgotten. These details are impor- 
tant as they tend to drive all other inter- 




Easy riding with sfrom "! 



The fastest way from design to production 



Tired of EPROM's erasing nightmare ? 
Challenged by Flash's in-circuit updatability 
Hampered by EEPROM's limited capacity ? 



Smart Flash ROM (SFROM) is (he optimal 
re-programmable device for non-volatile 
memory that enables quick and easy 
continuous write and rewrite without removal 
and without UV erase. 

SFROM is the only re-programmable device 
for non-volatile memory that incorporates large 
Hash storage capacity />/«.*■ in circuit remote 
re-programming capability with absolutely no 
design efforts. 



SFROM incorporates: 

• 256 Kbit to 16 Mbit flash memory 

• Self-loading peripheral memory for 
firmware and/or data storage 

• In circuit self re-programmability 

• On-chip UART for serial interface 

• I 2 C standard Interface 
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Headquarters: EUROM FlashWare Solutions Ltd. 

Atidim Industrial Park Bldg. I, P.O.B 56032, Tel Aviv 61580. Israel 
Tel: +972-3-490 920 Fax: +972-3-490 922 

USA Olfice; EUROM FlashWare Solutions Inc. 

4655 Old Ironsides Dnve, Suite 200. Santa Clara. CA 95054 
Tel: 408-748-9995 Fax: 408-748-8408 
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nal task sequencing. Faults, errors, and 
exception conditions are usually 
ignored but often constitute an impor- 
tant element of the design. 

For example, on a recent applica- 
tion, engineers described an existing 
system as having only two interrupts. 
A closer examination showed 23 inter- 
rupts, many of which had a direct bear- 
ing on the application. Only a few 
interrupts dealt with internal error con- 
ditions that halted the machine. Even 
this detail is needed, however, for 
complete understanding of the system. 
When the additional interrupts and the 
associated ISRs were added, a much 
clearer picture of the system operation 
emerged. 

The written descriptions, especially 
those parts involving the sequencing 
and control, should provide hints about 
what to add to make the drawings com- 
plete. It is possible to have too much 
detail, of course. For example, data- 
flow lines aren't needed for every data 
unit. Other kinds of design documenta- 
tion may supply that detail. As a rule, 
only the fact that data flows from task 
to task, directly or through some 
shared resource, is necessary for task- 
ing design descriptions. 

All documentation is difficult. 
Having a strategy and model in mind, 
however, makes the job much easier to 
cope with. If you don't normally docu- 
ment tasking designs, give this method 
a try on a smaller application to see 
how it works. If you have to provide a 
top-level design document for a sizable 
system, use this method as a starter and 
see if doesn't make your job more 
manageable. The result will provide a 
good road map from the system or top- 
level requirements down to the lower 
level detail design and code. M^.tl 

M.F. Moon is principal engineer in the 
Software Engineering Division at the 
Hughes Aircraft Co. in Fullerton, CA. 
where he has been developing embed- 
ded software for more that 27 years. 
He can be reached by telephone ax 
(714) 732-3569 or electronically m 
m. moon. @ieee. org. 



